---
layout: m1x_rest
title: Introduction to the Magento 1.x REST API
---


    <ul class="introduction-menu">
        <li><a href='#RESTAPIIntroduction-IntroductiontoAPI'><strong>Introduction to API</strong></a>
            <ul>
                <li><a href='#RESTAPIIntroduction-Overview'>概述</a></li>
                <li><a href='#RESTAPIIntroduction-OverallCapabilities'>Overall Capabilities</a></li>
                <li><a href='#RESTAPIIntroduction-Authentication'>Authentication</a></li>
                <li><a href='#RESTAPIIntroduction-OutputFormats'>Output Formats</a></li>
                <li><a href='#RESTAPIIntroduction-HTTPVerbs'>HTTP Verbs</a></li>
                <li><a href='#RESTAPIIntroduction-RequestStructure'>Request Structure</a></li>
                <li><a href='#RESTAPIIntroduction-RESTResources'>REST Resources</a>
                    <ul>
                        <li><a href='#RESTAPIIntroduction-Products'>Products</a>
                            <ul>
                                <li><a href='#RESTAPIIntroduction-ProductCategories'>Product Categories</a></li>
                                <li><a href='#RESTAPIIntroduction-ProductImages'>Product Images</a></li>
                                <li><a href='#RESTAPIIntroduction-ProductWebsites'>Product Websites</a></li>
                            </ul>
                        </li>
                        <li><a href='#RESTAPIIntroduction-Customers'>Customers</a></li>
                        <li><a href='#RESTAPIIntroduction-CustomerAddresses'>Customer Addresses</a></li>
                        <li><a href='#RESTAPIIntroduction-Inventory'>Inventory</a></li>
                        <li><a href='#RESTAPIIntroduction-SalesOrders'>Sales Orders</a>
                            <ul>
                                <li><a href='#RESTAPIIntroduction-OrderItems'>Order Items</a></li>
                                <li><a href='#RESTAPIIntroduction-OrderAddresses'>Order Addresses</a></li>
                                <li><a href='#RESTAPIIntroduction-OrderComments'>Order Comments</a></li>
                            </ul>
                        </li>
                    </ul>
                </li>
                <li><a href='#RESTAPIIntroduction-PreparingforRESTAPI'>Preparing for REST API</a></li>
                <li><a href='#RESTAPIIntroduction-PreparingRESTAPIfortheThirdPartyApplication'>Preparing REST API for the Third-Party Application</a></li>
                <li><a href='#RESTAPIIntroduction-PHPExamples'>PHP Examples</a>
                    <ul>
                        <li><a href='#RESTAPIIntroduction-CreateasimpleproductasanAdminuserwithOAuthauthentication'>Create a simple product as an Admin user with OAuth authentication</a></li>
                        <li><a href='#RESTAPIIntroduction-RetrievethelistofproductsasaCustomeruserwithOAuthauthentication'>Retrieve the list of products as a Customer user with OAuth authentication</a></li>
                    </ul>
                </li>
                <li><a href='#RESTAPIIntroduction-RESTClientExample'>REST Client Example</a></li>
            </ul>
        </li>
    </ul>



<h2><a name="RESTAPIIntroduction-IntroductiontoAPI"></a>Introduction to API</h2>

<h3><a name="RESTAPIIntroduction-Overview"></a>概述</h3>

<p>What is REST API? To make it simple, REST API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the HTTP protocol. An advantage of such an approach is the wide usage of HTTP. That is why REST API can be used practically for any programming language.</p>

<p>Common characteristics of Magento REST API resources are as follows: (<b>magentohost</b> is your domain)</p>

<ul>
    <li>You access the resource by sending an HTTP request to the Magento API server. The server replies with a response that contains either the data you requested, or the status indicator, or even both.</li>
    <li>All resources are located at <a href="https://magentohost/api/rest/">https://magentohost/api/rest/</a>.</li>
    <li>All resources may return different HTTP status codes (e.g., HTTP Status Code 200 for success response or HTTP Status Code 400 for the bad request).</li>
    <li>You request a particular resource by adding a particular path to the base URL that specifies the resource.</li>
</ul>


<h3><a name="RESTAPIIntroduction-OverallCapabilities"></a>Overall Capabilities</h3>

<p>Magento REST API allows managing a number of features, namely:</p>

<ul>
    <li>Managing customers.</li>
    <li>Managing customer addresses.</li>
    <li>Managing products.</li>
    <li>Retrieving sales orders.</li>
    <li>Managing inventory.</li>
</ul>



<h3><a name="RESTAPIIntroduction-Authentication"></a>Authentication</h3>

<p>Magento REST API uses 3-legged <a href="http://tools.ietf.org/html/rfc5849">OAuth 1.0a</a> protocol to authenticate the application to access the Magento service.</p>


<h3><a name="RESTAPIIntroduction-OutputFormats"></a>Output Formats</h3>

<p>The REST API supports the response in two formats, which are XML and JSON.</p>

<h3><a name="RESTAPIIntroduction-HTTPVerbs"></a>HTTP Verbs</h3>

<p>HTTP verbs are used to manage the state of resources. In Magento REST API, there are four verbs used to manage resources: GET, POST, PUT, and DELETE. You can get the contents of the data using HTTP GET, delete the data using HTTP DELETE, and create or update the data using POST/PUT.</p>

<h3><a name="RESTAPIIntroduction-RequestStructure"></a>Request Structure</h3>

<p>All URLs in REST API have the following base URL.&nbsp;</p>

<p><a href="http://magentohost/api/rest/">http://magentohost/api/rest/</a></p>


<p><b>Example</b></p>

<p>Supposing, you want to retrieve the list of customers from Magento. To do this, you need to use the GET HTTP method. The GET request to retrieve the list of customers will look as follows:</p>

<div class="panel" style="border-width: 1px;"><div class="panelContent">
    <p><a href="http://magentohost/api/rest/customers">http://magentohost/api/rest/customers</a></p>
</div></div>

<p>where</p>

<ul>
    <li><a href="http://magentohost/api/rest/">http://magentohost/api/rest/</a> &#45; endpoint</li>
    <li>/customers - action URL</li>
</ul>


<h3><a name="RESTAPIIntroduction-RESTResources"></a>REST Resources</h3>

<p>The Magento REST API allows you to manage customers, customer addresses, sales orders, inventory, and products. REST API is organized into the following categories:</p>

<h5><a name="RESTAPIIntroduction-Products"></a>Products</h5>

<ul>
    <li>Retrieve the list of products, create, update, and delete a product.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/products">http://magentohost/api/rest/products</a></li>
</ul>


<h6><a name="RESTAPIIntroduction-ProductCategories"></a>Product Categories</h6>

<ul>
    <li>Retrieve the list of categories assigned to a product, assign, and unassign the category to/from the specific product.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/products/:productId/categories">http://magentohost/api/rest/products/:productId/categories</a></li>
</ul>


<h6><a name="RESTAPIIntroduction-ProductImages"></a>Product Images</h6>

<ul>
    <li>Retrieve the list of images assigned to a product, add, update, and remove an image to/from the specific product.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/products/:productId/images">http://magentohost/api/rest/products/:productId/images</a></li>
</ul>


<h6><a name="RESTAPIIntroduction-ProductWebsites"></a>Product Websites</h6>

<ul>
    <li>Retrieve the list of websites assigned to a product, assign, and unassign a  website to/from the specific product.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/products/:productId/websites">http://magentohost/api/rest/products/:productId/websites</a></li>
</ul>


<h5><a name="RESTAPIIntroduction-Customers"></a>Customers</h5>

<ul>
    <li>Retrieve the list of customers, create, delete a customer, and update the customer information.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/customers">http://magentohost/api/rest/customers</a></li>
</ul>


<h5><a name="RESTAPIIntroduction-CustomerAddresses"></a>Customer Addresses</h5>

<ul>
    <li>Retrieve the list of customer addresses, create, update, and delete the customer address.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/customers/:customerId/addresses">http://magentohost/api/rest/customers/:customerId/addresses</a></li>
</ul>


<h5><a name="RESTAPIIntroduction-Inventory"></a>Inventory</h5>

<ul>
    <li>Retrieve the list of stock items and update required stock items.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/stockitems">http://magentohost/api/rest/stockitems</a></li>
</ul>


<h5><a name="RESTAPIIntroduction-SalesOrders"></a>Sales Orders</h5>

<ul>
    <li>Retrieve the list of sales orders as well as the specific order information.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/orders">http://magentohost/api/rest/orders</a></li>
</ul>


<h6><a name="RESTAPIIntroduction-OrderItems"></a>Order Items</h6>

<ul>
    <li>Retrieve order items for the specific order.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/orders/:orderId/items">http://magentohost/api/rest/orders/:orderId/items</a></li>
</ul>


<h6><a name="RESTAPIIntroduction-OrderAddresses"></a>Order Addresses</h6>

<ul>
    <li>Retrieve information on order billing and shipping addresses for the specific order.<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/orders/:orderId/addresses">http://magentohost/api/rest/orders/:orderId/addresses</a></li>
</ul>


<h6><a name="RESTAPIIntroduction-OrderComments"></a>Order Comments</h6>

<ul>
    <li>Retrieve order comments for the specific order<br/>
        <b>Resource Structure</b>: <a href="http://magentohost/api/rest/orders/:orderId/comments">http://magentohost/api/rest/orders/:orderId/comments</a></li>
</ul>


<h3><a name="RESTAPIIntroduction-PreparingforRESTAPI"></a>Preparing for REST API</h3>

<p>These steps are required for utilizing REST API resources:</p>

<ol>
    <li>Set up permissions for REST resource operations from Magento Admin Panel.</li>
    <li>Configure the attributes for different users types in Magento Admin Panel. There are 3 different types of users in accessing the data: Admin, Customer, and Guest. Admin is the backend logged in user, Customer is the fronted logged in user, and Guest is a non-logged in fronted user.</li>
</ol>


<h3><a name="RESTAPIIntroduction-PreparingRESTAPIfortheThirdPartyApplication"></a>Preparing REST API for the Third-Party Application</h3>

<ol>
    <li>Register the third-party application (Consumer) in Magento Admin Panel.</li>
    <li>The third-party application will utilize the provided consumer credentials to call Magento store for getting the access token to access the data.</li>
</ol>


<p><span class="image-wrap" style=""><img src="{{ site.baseurl }}/common/images/m1x/rest-intro1.png" style="border: 1px solid black"/></span></p>

<h3><a name="RESTAPIIntroduction-PHPExamples"></a>PHP Examples</h3>


<h4><a name="RESTAPIIntroduction-CreateasimpleproductasanAdminuserwithOAuthauthentication"></a>Create a simple product as an Admin user with OAuth authentication</h4>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
    <div id="root">
		<pre class="theme: Default; brush: php; gutter: false">&lt;?php
/**
* Example of simple product POST using Admin account via Magento REST API. OAuth authorization is used
*/
$callbackUrl = "http://yourhost/oauth_admin.php";
$temporaryCredentialsRequestUrl = "http://magentohost/oauth/initiate?oauth_callback=" . urlencode($callbackUrl);
$adminAuthorizationUrl = 'http://magentohost/admin/oauth_authorize';
$accessTokenRequestUrl = 'http://magentohost/oauth/token';
$apiUrl = 'http://magentohost/api/rest';
$consumerKey = 'yourconsumerkey';
$consumerSecret = 'yourconsumersecret';

session_start();
if (!isset($_GET['oauth_token']) &amp;&amp; isset($_SESSION['state']) &amp;&amp; $_SESSION['state'] == 1) {
    $_SESSION['state'] = 0;
}
try {
    $authType = ($_SESSION['state'] == 2) ? OAUTH_AUTH_TYPE_AUTHORIZATION : OAUTH_AUTH_TYPE_URI;
    $oauthClient = new OAuth($consumerKey, $consumerSecret, OAUTH_SIG_METHOD_HMACSHA1, $authType);
    $oauthClient-&gt;enableDebug();

    if (!isset($_GET['oauth_token']) &amp;&amp; !$_SESSION['state']) {
        $requestToken = $oauthClient-&gt;getRequestToken($temporaryCredentialsRequestUrl);
        $_SESSION['secret'] = $requestToken['oauth_token_secret'];
        $_SESSION['state'] = 1;
        header('Location: ' . $adminAuthorizationUrl . '?oauth_token=' . $requestToken['oauth_token']);
        exit;
    } else if ($_SESSION['state'] == 1) {
        $oauthClient-&gt;setToken($_GET['oauth_token'], $_SESSION['secret']);
        $accessToken = $oauthClient-&gt;getAccessToken($accessTokenRequestUrl);
        $_SESSION['state'] = 2;
        $_SESSION['token'] = $accessToken['oauth_token'];
        $_SESSION['secret'] = $accessToken['oauth_token_secret'];
        header('Location: ' . $callbackUrl);
        exit;
    } else {
        $oauthClient-&gt;setToken($_SESSION['token'], $_SESSION['secret']);
        $resourceUrl = "$apiUrl/products";
        $productData = json_encode(array(
            'type_id'           =&gt; 'simple',
            'attribute_set_id'  =&gt; 4,
            'sku'               =&gt; 'simple' . uniqid(),
            'weight'            =&gt; 1,
            'status'            =&gt; 1,
            'visibility'        =&gt; 4,
            'name'              =&gt; 'Simple Product',
            'description'       =&gt; 'Simple Description',
            'short_description' =&gt; 'Simple Short Description',
            'price'             =&gt; 99.95,
            'tax_class_id'      =&gt; 0,
        ));
        $headers = array('Content-Type' =&gt; 'application/json');
        $oauthClient-&gt;fetch($resourceUrl, $productData, OAUTH_HTTP_METHOD_POST, $headers);
        print_r($oauthClient-&gt;getLastResponseInfo());
    }
} catch (OAuthException $e) {
    print_r($e);
}</pre>
    </div>
</div></div>

<h4><a name="RESTAPIIntroduction-RetrievethelistofproductsasaCustomeruserwithOAuthauthentication"></a>Retrieve the list of products as a Customer user with OAuth authentication</h4>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
    <div id="root">
		<pre class="theme: Default; brush: php; gutter: false">&lt;?php
/**
 * Example of products list retrieve using Customer account via Magento REST API. OAuth authorization is used
 */
$callbackUrl = "http://yourhost/oauth_customer.php";
$temporaryCredentialsRequestUrl = "http://magentohost/oauth/initiate?oauth_callback=" . urlencode($callbackUrl);
$adminAuthorizationUrl = 'http://magentohost/oauth/authorize';
$accessTokenRequestUrl = 'http://magentohost/oauth/token';
$apiUrl = 'http://magentohost/api/rest';
$consumerKey = 'yourconsumerkey';
$consumerSecret = 'yourconsumersecret';

session_start();
if (!isset($_GET['oauth_token']) &amp;&amp; isset($_SESSION['state']) &amp;&amp; $_SESSION['state'] == 1) {
    $_SESSION['state'] = 0;
}
try {
    $authType = ($_SESSION['state'] == 2) ? OAUTH_AUTH_TYPE_AUTHORIZATION : OAUTH_AUTH_TYPE_URI;
    $oauthClient = new OAuth($consumerKey, $consumerSecret, OAUTH_SIG_METHOD_HMACSHA1, $authType);
    $oauthClient-&gt;enableDebug();

    if (!isset($_GET['oauth_token']) &amp;&amp; !$_SESSION['state']) {
        $requestToken = $oauthClient-&gt;getRequestToken($temporaryCredentialsRequestUrl);
        $_SESSION['secret'] = $requestToken['oauth_token_secret'];
        $_SESSION['state'] = 1;
        header('Location: ' . $adminAuthorizationUrl . '?oauth_token=' . $requestToken['oauth_token']);
        exit;
    } else if ($_SESSION['state'] == 1) {
        $oauthClient-&gt;setToken($_GET['oauth_token'], $_SESSION['secret']);
        $accessToken = $oauthClient-&gt;getAccessToken($accessTokenRequestUrl);
        $_SESSION['state'] = 2;
        $_SESSION['token'] = $accessToken['oauth_token'];
        $_SESSION['secret'] = $accessToken['oauth_token_secret'];
        header('Location: ' . $callbackUrl);
        exit;
    } else {
        $oauthClient-&gt;setToken($_SESSION['token'], $_SESSION['secret']);
        $resourceUrl = "$apiUrl/products";
        $oauthClient-&gt;fetch($resourceUrl, array(), 'GET', array('Content-Type' => 'application/json', 'Accept' => '*/*'));
        $productsList = json_decode($oauthClient-&gt;getLastResponse());
        print_r($productsList);
    }
} catch (OAuthException $e) {
    print_r($e);
}</pre>
    </div>
</div></div>

<h3><a name="RESTAPIIntroduction-RESTClientExample"></a>REST Client Example</h3>

<p>Retrieving the list of Products as a Guest</p>

<ol>
    <li>Use the <a href="https://addons.mozilla.org/en-US/firefox/addon/restclient/">REST Client</a> that is a FireFox add-on. In the REST Client, in the <b>Method</b> drop-down list, select the <b>GET</b> option.</li>
    <li>In the URL field, enter the following URL: <a href="http://magentohost/api/rest/products?limit=2">http://magentohost/api/rest/products?limit=2</a>.</li>
    <li>Click <b>Send</b>. Information about the products will be displayed in the response body. Example in the XML format is as follows:</li>
</ol>


<p><b>Example: XML</b></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
    <div id="root">
		<pre class="theme: Default; brush: java; gutter: false">&lt;?xml version="1.0"?&gt;
&lt;magento_api&gt;
  &lt;data_item&gt;
    &lt;entity_id&gt;16&lt;/entity_id&gt;
    &lt;type_id&gt;simple&lt;/type_id&gt;
    &lt;sku&gt;n2610&lt;/sku&gt;
    &lt;description&gt;The Nokia 2610 is an easy to use device that combines multiple messaging options including email, instant messaging, and more. You can even download MP3 ringtones, graphics, and games straight to the phone, or surf the Internet with Cingular's MEdia Net service. It's the perfect complement to Cingular service for those even remotely interested in mobile Web capabilities in an affordable handset.
Design
Compact and stylish, the 2610 features a candybar design sporting a bright 128 x 128 pixel display capable of displaying over 65,000 colors. Most of the phone's features and on-screen menus are controlled by a center toggle on the control pad. A standard hands-free headphone jack is provided, as are volume control keys, and there's even a "Go-To" button that can be assigned by the user for quick access to favorite applications. Lastly, the included speakerphone allows you to talk handsfree, and because the phone sports an internal antenna, there's nothing to snag or break off.
&lt;/description&gt;
    &lt;meta_keyword&gt;Nokia 2610, cell, phone, &lt;/meta_keyword&gt;
    &lt;short_description&gt;The words "entry level" no longer mean "low-end," especially when it comes to the Nokia 2610. Offering advanced media and calling features without breaking the bank&lt;/short_description&gt;
    &lt;name&gt;Nokia 2610 Phone&lt;/name&gt;
    &lt;meta_title&gt;Nokia 2610&lt;/meta_title&gt;
    &lt;meta_description&gt;Offering advanced media and calling features without breaking the bank, The Nokia 2610 is an easy to use&lt;/meta_description&gt;
    &lt;regular_price_with_tax&gt;149.99&lt;/regular_price_with_tax&gt;
    &lt;regular_price_without_tax&gt;149.99&lt;/regular_price_without_tax&gt;
    &lt;final_price_with_tax&gt;149.99&lt;/final_price_with_tax&gt;
    &lt;final_price_without_tax&gt;149.99&lt;/final_price_without_tax&gt;
    &lt;is_saleable&gt;1&lt;/is_saleable&gt;
    &lt;image_url&gt;http://magentohost/imageulr/nokia.jpg&lt;/image_url&gt;
  &lt;/data_item&gt;
  &lt;data_item&gt;
    &lt;entity_id&gt;17&lt;/entity_id&gt;
    &lt;type_id&gt;simple&lt;/type_id&gt;
    &lt;sku&gt;bb8100&lt;/sku&gt;
    &lt;description&gt; Like the BlackBerry 7105t, the BlackBerry 8100 Pearl is
The BlackBerry 8100 Pearl sports a large 240 x 260 screen that supports over 65,000 colors-- plenty of real estate to view your e-mails, Web browser content, messaging sessions, and attachments. The venerable BlackBerry trackwheel has been replaced on this model with an innovative four-way trackball placed below the screen. On the rear of the handheld, you'll find a 1.3-megapixel camera and a self portrait mirror. The handheld's microSD memory card slot is located inside the device, behind the battery. There's also a standard 2.5mm headset jack that can be used with the included headset, as well as a mini-USB port for data connectivity.&lt;/description&gt;
    &lt;meta_keyword&gt;Blackberry, 8100, pearl, cell, phone&lt;/meta_keyword&gt;
    &lt;short_description&gt;The BlackBerry 8100 Pearl is a departure from the form factor of previous BlackBerry devices. This BlackBerry handset is far more phone-like, and RIM's engineers have managed to fit a QWERTY keyboard onto the handset's slim frame.&lt;/short_description&gt;
    &lt;name&gt;BlackBerry 8100 Pearl&lt;/name&gt;
    &lt;meta_title&gt;BlackBerry 8100 Pearl&lt;/meta_title&gt;
    &lt;meta_description&gt;BlackBerry 8100 Pearl sports a large 240 x 260 screen that supports over 65,000 colors-- plenty of real estate to view your e-mails, Web browser content, messaging sessions, and attachments.&lt;/meta_description&gt;
    &lt;regular_price_with_tax&gt;349.99&lt;/regular_price_with_tax&gt;
    &lt;regular_price_without_tax&gt;349.99&lt;/regular_price_without_tax&gt;
    &lt;final_price_with_tax&gt;349.99&lt;/final_price_with_tax&gt;
    &lt;final_price_without_tax&gt;349.99&lt;/final_price_without_tax&gt;
    &lt;is_saleable&gt;1&lt;/is_saleable&gt;
    &lt;image_url&gt;http://magentohost/imageulr/blackberry.jpg&lt;/image_url&gt;
  &lt;/data_item&gt;
&lt;/magento_api&gt;</pre>
    </div>
</div></div>

<p><b>Additional Information</b></p>

<p>You can define the limit of items returned in the response by passing the limit parameter. By default, 10 items are returned and the maximum number is 100 items. You can also define the page number by passing the page parameter. Example:</p>

<div class="panel" style="border-width: 1px;"><div class="panelContent">
    <p><a href="http://magentohost/api/rest/products?page=2&amp;limit=20">http://magentohost/api/rest/products?page=2&amp;limit=20</a></p>
</div></div>

<p>Authorization header will be required for Admin and Customer user types. The following parameters must be provided in the Authorization header for the call:</p>
<ul>
    <li>oauth_consumer_key - the Consumer Key value provided after the registration of the application.</li>
    <li>oauth_nonce - a random value, uniquely generated by the application.</li>
    <li>oauth_signature_method - name of the signature method used to sign the request. Can have one of the following values: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.</li>
    <li>oauth_signature - a generated value (signature).</li>
    <li>oauth_timestamp - a positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.</li>
    <li>oauth_token - the oauth_token value (Request Token).</li>
    <li>oauth_version - OAuth version.</li>
</ul>
<br/>
<?php include(__ROOT__ . 'footer.php'); ?>
